Welcome back to another installment of the 12 days of (CommandBox) Christmas.  One thing I love about this season is the traditions that our family does over and over each year.  Another thing worth doing over and over the same way is staring your CommandBox servers!  That's why we have server.json-- your key to repeatable, consistent server starts.

What is server.json?

Just like the recipe your grandma used every year for the Christmas ham, your server.json file is the recipe for how you'd like CommandBox to start up your servers.  This ensures that not only you get the same settings applied every time, but that the other developers on your team can also get the same local environment.  And all this with no traditional server installations, IIS, Apache, or Tomcat!

The server.json file lives by default in your web root and will get picked up automatically when you start up a server in that directory. 

{
    "name":"mySite",
    "openBrowser":"false",
    "app":{
        "cfengine":"lucee@5"
    },
    "jvm":{
        "heapSize":"1024"
    }
}

Have more than one server you like to start for testing the same site?  No worries-- you can actually name the files anything you want and just point the start command at the file you want it to use.

server start mySiteAdobe11.json

Not too excited about storing the json file in your web root?  That's cool-- put it wherever you like, and use a relative or absolute path to tell CommandBox where the webroot is in relation to the file.  

{
    "name":"mySite",
    "web":{
        "webroot":"www/"
    }
}

You'll likely want to commit your server.json file to your source control repo.  Remember, that all file paths can be relative to the location of the JSON file to keep it portable.  This means that all a new developer needs to do in order to get up and running on their first day (after installing CommandBox) is create an empty folder and run:

git clone https://yourRepoUrl.git
box install
box start

Servlet settings

You can control any settings that would normally be a part of Tomcat (or in this case, Undertow) and the JVM.  These include:

• Java heap size
• What version of Java to use
• Custom JVM args
• Default welcome files (like index.cfm)

Web server settings

CommandBox has a well-featured Java-based web server built in which means you probably don't need IIS or Apache for your local development. In your server.json you can control the following:

• URL rewrites
• HTTP/HTTPS/AJP ports
• SSL certs
• Virtual directories
• Custom error pages for 404, 500, etc
• Enable/disable directory browsing
• Host name
• Basic auth

ColdFusion Server

You can also choose what CF engine you want to be used as well as the version.

• Adobe CF
• Lucee Server
• Railo
• Any Java-based WAR! (Like Jenkins, OpenBD, etc)
• You'll get the latest CF engine, but specify a version like
  • adobe@11
  • lucee@4.5
  • adobe@10.0.21+300068

If you're wondering about the settings you set in the web based administrator for your server, we have a module for that called CFConfig.  Stay tuned and we'll cover that soon in another blog.

But wait, there's more!

I've only mentioned the basics here to get to started.  For a full list of every property you can place in your server.json file, check out our comprehensive docs.  

https://commandbox.ortusbooks.com/embedded-server/server.json

Also remember that CommandBox has full tab completion built in.  You can edit your server.json file manually with a text editor or IDE, or you can also manage it from the CLI with the server show, server set, and server clear commands.  This is great for automation or just quick edits from the command line.  To see all the possible values you can type, enter "server set" from the interactive shell and hit the tab key.  Autocomplete will kick in and show you all the possibilities.  Continue to use tab completion as you type to make sure you're spelling everything right!

Modules

CommandBox modules can also look for properties of their own in your server.json file.  There's no limit to what you can store in the JSON file and no restrictions on how it can be used.  One example is the commandbox-fusionreactor module which will look for your FusionReactor license and settings there.  You can check the documentation for modules such as this one and they will tell you what properties to create.